fix(mf4): defer asammdf imports until reader/writer construction - #2123

Summary of Changes

Importing asammdf first can re-enter can through canmatrix/canopen before asammdf finishes initializing. The optional-import guard then permanently treats an installed dependency as missing.

• Load asammdf when an MF4 reader or writer is constructed.
• Report a genuinely missing asammdf package separately from a missing transitive dependency, before opening the output file.
• Cover native import orders, a deterministic circular import, missing dependencies and file-opening controls.
• Integrate current main while preserving UTC writer timestamps and the packed error-frame repair from fix(mf4): read packed error-frame payloads without losing byte order #2115. Its eight payload regressions retain their assertions and import helper classes/constants directly from asammdf.
• Preserve evaluated public path annotations for Sphinx while keeping asammdf signature types behind type checking.

Closes #2122. Thanks to @nehalkpatel for the reproduction and dependency-chain analysis.

Type of Change

• Bug fix

Checklist

• Contribution guide followed; tests and changelog fragment included.
• Focused regressions and applicable local static checks pass.
• All checks and tests pass (tox): limitations below remain.

Current validation — 13 November 2026

Published revision dcbe0e4394b7286aaa4326557b7bc8805348fd4f merges upstream 86e85794f6c3505c988a4acd5d34f5b08f508b17 into the existing PR. Its complete tree c2d30628aaaeff97d88042704a8a4e3e9d018f2f matches the final locally verified tree.

Environment: Linux / CPython 3.12.14; asammdf 8.7.2, canmatrix 1.2, canopen 2.4.1. The shallow checkout used a local setuptools-scm version override for installation.

• Final focused MF4 suite: 16 passed, 1 existing unsupported-append skip, 6 subtests passed. This includes the eight upstream packed-payload cases.
• Identical import regressions on unchanged current upstream fail in four reader/writer subcases and the transitive-error case; all pass with this repair.
• Full final local suite: 529 passed, 99 skipped, 42 subtests passed, 28 failed. Baseline with the same added import tests: 528 passed, 99 skipped, 38 subtests passed, 33 failed. Every remaining candidate failure is an IPv4/IPv6 multicast initialization failure also present on the baseline; there are no new failing test identities.
• Project-wide Black and Ruff, changed-source Pylint and whitespace checks pass. Mypy targets Python 3.11–3.15 pass all 65 source files in a separate environment without MF4 extras, matching the type-check environment's optional-dependency boundary. With real MF4 dependencies installed, a separate diagnostic retains seven errors versus 16 on the baseline.
• 39 documentation doctests pass. Strict HTML documentation generation retains one unresolved _thread.allocate_lock reference also present on unchanged upstream. The introduced path-annotation reference warning was repaired; no warning suppression was added.
• Independent inspection and runtime probes found no material issue; importing can leaves asammdf unloaded, and writer UTC start time and message writing remain valid.

No native Python 3.14 tox run, hosted CI success for this new revision, physical CAN hardware, other OS/interpreter runtime matrix, or minimum asammdf 6 validation is claimed. Full local tests and strict HTML documentation are not completely green for the inherited/environment limitations above.

Prepared with OpenAI Codex assistance and independent inspection.

Timothy Anderson — Spotted Ridge Engineering / OC Labs
Independent software verification · GDN (Global Decision Network)
timothyanderson096@gmail.com · Engineering evidence